The jdoc application was developed as a tool for displaying online manuals for Tk¡based applications. It can be used to display other kinds of multi¡font hypertext documents as well. In addition to being able to follow hypertext links, you can quickly jump to any major section in the document you're viewing.
The jdoc document viewer is distributed as part of the jstools package.
This help file describes jdoc version 3.6/3.0.
The jdoc viewer is a rewrite of jhelp, which was used to display help files in previous releases of jstools. Unfortunately, jdoc can't read jhelp's file format. A version of jhelp is included with jstools 3.6/3.0 for people who want to read documentation in the old format, but I'm no longer maintainng it, and it probably won't be distributed with future versions of jstools.
Copyright and contact information is available in the jstools documentation.
Invocation
jdoc [topic]
To view a document, type `jdoc topic' at the Unix shell prompt, assuming jdoc is in your path. You'll get an error message if no file can be found for the topic you specify. If the requested topic can't be found, an alert box will tell you so.
The jdoc application is used to display help files for jstools applications, so it is also invoked for you by those applications when you choose their `Help' commands.
See Documents for information on how jdoc looks up topic names.
If you don't specify topic, you'll be prompted to choose a document from a list of available topics.
Buttons
There are three buttons at the bottom of the document window:
Done
The `Done' button closes the window and quits the document viewer. (It's the same as choosing `Quit' from the `Doc Viewer' menu.)
Load...
The `Load...' button brings up a panel that lets you choose a new document from a list. (It's the same as choosing `Load...' from the `Document' menu.) See Documents for information on how jdoc finds the available documents.
Print
The `Print' button sends the document as PostScript to the current printer, after asking for confirmation. (It's the same as choosing `Print' from the `Document' menu.)
Find...
The `Find...' button brings up the Find Panel, which lets you search for text in the document you're viewing. (It's the same as choosing `Find...' from the `Document' menu.)
The Sections Menu
The sections of the document are listed under the `Sections' menu (where each top¡level heading starts a new section), and you can jump to a particular section by choosing it from the menu. The document window will scroll so that the section you chose is displayed at the top. (Of course, you can also scroll through the document with the scrollbar.)
The Document Menu
Load...
Choosing `Load...' from the `Document' menu brings up a panel that lets you choose a new document from a list of the available documents. (See for information on how jdoc finds the available documents.) To choose a document, click on its name to select it, and then click `OK'. (You can also double¡click on a title, but there's a bug that sometimes pops up a harmless error message when you do.)
Save As...
Choosing `Save As...' from the `Document' menu brings up a File Selector Panel that lets you save the current document in one of three formats: TeX source, HTML, or the Tcl¡syntax rich¡text format used by the jrichtext.tcl library. If you have TeX available, saving a document as TeX source and typesetting that is probably the best way to get hardcopy of a jdoc document.
Print
Choosing `Print' from the `Document' menu pops up a panel asking you to confirm that you want to print to the current printer, which must be a PostScript printer. If you click OK, the document you're viewing is converted to PostScript and the PostScript is sent to the printer.
If you don't have a PostScript printer, you may be able to generate hardcopy using one of the formats available via the `Save As...' command.
Find...
Choosing `Find...' from the `Document' menu brings up the Find Panel, which lets you search for text in the document you're viewing.
The Doc Viewer Menu
Help with Doc Viewer
You can get help about the jdoc application - this file - by choosing `Help with Doc Viewer' from the `Help' menu. This starts up another copy of jdoc displaying jdoc's help document.
About the Doc Viewer...
`About the Doc Viewer' under the `Help' menu displays an information panel with copyright information. The panel also lets you get more information about the author (me), and about the Tk/Tcl scripting environment..
Global Preferences...
This command brings up the jstools Global Preferences panel, which lets you set preferences common to all the jstools applications.
Doc Viewer Preferences...
This command brings up the jdoc preferences panel, described below under Doc Viewer Preferences.
Issue Tcl Command...
`Issue Tcl Command...' brings up a panel that prompts you for a Tcl command to be executed. This is mainly useful for debugging.
Issue Unix Command...
This brings up a panel that prompts you for a Unix command to be executed. If the command produces any output, it will be displayed; otherwise you'll see a notice to that effect. If there are any errors in the execution of the command, you'll see an error dialogue box with the error message returned by the command. This command doesn't have any effect on the document you're viewing; it's just a convenience.
Quit
This quits the program (asking for confirmation first if you've chosen `Confirm Actions' on the Global Preferences panel). It's the same as clicking the Quit button.
Documents
The documents displayed by jdoc are files in a rich¡text format that can be created and edited by jedit's jdoc mode. The actual file format is the same as that used by the richtext mode of jedit. Their names must end in .jdoc. (By default, jedit will open or create files ending in .jdoc in its jdoc mode, and it will open or create files ending in .jrt in its richtext mode.)
In some circumstances, such as specifying a topic on the command line, you can leave off the trailing .jdoc from a document name; it doesn't hurt to include it, though.
How Documents Are Found
If a document is specified as a full pathname, that file is opened. If (as is usually the case) a relative pathname is specified, however, the following directories will be searched for the file until it is found:
* the current directory
* tk/jdoc in your home directory
* .tk/jdoc in your home directory
* jdoc in the system¡wide jstools library directory (typically /usr/local/lib/jstools)
* jdoc in the system¡wide Tk library directory (typically /usr/local/lib/tk)
A relative pathname can include a directory component, so that for instance the document name jeditmodes/jdoc.jdoc would find a file named /usr/local/lib/jstools/jdoc/jeditmodes/jdoc.jdoc. This is useful for grouping related documents together, and for `hiding' documents that are designed to be referenced only from within other documents, rather than being selected by the user.
When you choose `Load...' or invoke jdoc without a document name, jdoc constructs the list of available documents by looking for files ending in .jdoc in the above directories. (However, it doesn't search subdirectories of the above directories.)
Creating Documents
Note: This material is covered in more detail in the documentation for jedit's jdoc mode.
To create a document for display by jdoc, simply edit a file whose name ends in .jdoc with the jedit editor. A `jdoc' menu will be available to help you construct cross¡references, and the `Format' menu will let you compose multi¡font text.
The very first line of your document should be an overall title for the document, and you should use `Make Overall Topic Title' to put this in the right font. (It's possible that future versions of jdoc will use this when constructing the list of available topics, or when converting to other formats.) No other text in the document should be marked as an overall topic title.
The document should be divided into sections, and each section should have a section title (created with `Make Section Title'). The user will be able to navigate among these sections with the Sections menu, which is constructed from the section titles. (In the future, some sort of automatic table¡of¡contents or index may also use this information.)
You can further divide a section by preceding subsections with a subsection heading with `Make Subsection Heading'. If you need further subdivisions, you can use the various heading styles under the `Font' sub¡menu of the `Format' menu.
You can create a cross reference to another document by highlighting the document name (or the phrase you want to link to the document) and choosing `Cross Reference...'. A panel will appear asking you to confirm (or specify) the document to link to. You need to include the trailing .jdoc in the document name.
You can also make a cross¡reference to another point in the current document by using a hash mark (#) followed by an anchor name (for which see below) instead of a document name. For instance, `#Preferences' would link to the anchor named `Preferences' in the current document.
An anchor is a particular piece of text (typically a heading or subheading) which is given a particular name. The anchor name isn't actually displayed anywhere when the user is viewing the document, and it is entirely arbitrary. It's only used to identify a particular position in the text. (For this reason, it's not useful to have more than one anchor in a document with the same name.)
You can create an anchor by selecting text and choosing `Anchor Name...'; a name will be suggested for you based on the selected text. An anchor name should not have any spaces or `+' or `-' signs in it.
You can link to a particular point in another document by specifying the document name, then a hash mark, then the anchor name. For instance, `jstools.jdoc#Usage' would link to the anchor named `Usage' in the document jstools.jdoc.
(You can also create links to http: and ftp: URL's, as used by the World Wide Web, by specifying the full URL, and to HTML documents by specifying a pathname ending in .html, but these will only be displayed properly if Mosaic is available. See also Future Directions.)
You can link to a Unix manual page entry by selecting the manual page name and choosing `Man Page Reference'.
The `Show Tags at Insert' command is useful for figuring out the name of an anchor, or what a cross¡reference is pointing to.
Doc Viewer Preferences...
Choosing `Doc Viewer Preferences...' from the `Doc Viewer' menu brings up the Doc Viewer Preferences panel, which lets you customise the appearance of the text window that displays a document. It lets you set the overall width and height of the window (in characters), the colours used to display your text, the width of the raised border drawn around selected text, and the width of the blank border around the entire text window.
The buttons labelled `RGB' let you select a colour by manipulating sliders that represent the individual red, green, and blue components of the colour you're choosing. The buttons labelled `Name' let you select a colour by name, from the list of colours known on your system.
(Note: If the name of the colour database on your system isn't /usr/lib/X11/rgb.txt, then the `Name' colour buttons won't list all the colours available.)
(Many of the preferences you can set in the jstools Global Preferences panel also affect the document viewer. You can bring up the Global Preferences panel by choosing `Global Preferences...' from the `Doc Viewer' menu.)
Doc Viewer preferences are stored in the file ~/.tk/jdoc-defaults. (Global preferences are saved in the file ~/.tk/defaults.)
Customising jdoc
jdoc supports the standard jstools customisation mechanisms. You should consult the general jstools customisation documentation as well as the description below.
The ~/.tk/jdoc.tcl startup script
The file ~/.tk/jdocrc.tcl can contain Tcl code to customise your document viewing environment. For most purposes, you'll need to know Tcl and Tk, and look at the code for the document viewer, in order to create a useful startup script. (You may also find it useful to look at the documentation for the various jstools libraries, which are used extensively by the file viewer.)
Sample files
If jdoc was installed normally at your site, the directory /usr/local/lib/tk/jdoc/samples should contain some example files which you can copy, rename appropriately, and modify to your liking. (You may also find it useful to look at the jdoc script itself, and for information about Tcl syntax you should consult the various Tcl and Tk man pages.)
Evolution
Feel free to report bugs (and feature requests) to me, <js@bu.edu>, and I will try to deal with them. Also, feel free to fix bugs or add features on your own and let me know how you did it.
Bugs and Misfeatures
* The behaviour of the Find panel (searching from an invisible insert point) is confusing.
* If you move the mouse while double¡clicking on a title in the `Load...' panel, a bug in the mouse bindings is triggered and pops up a notification panel.
* The `Load...' panel should be a lot fancier. Perhaps there should be a database of document titles, as distinct from filenames, and the `Load...' panel should display the longer titles.
* When you `Save As...', hypertext links are lost in the saved file, even if you're saving in a format that supports the concept.
* The underlining that indicates links hides the underscore character; this is a particular problem with programming documentation.
Future Directions
* There should be preferences for fonts.
* The user should be able to customise how links are shown, perhaps using a different colour or a raised border instead of underlining them.
* There should be a straightforward way to print from within the application.
* I want to standardise bindings for non¡editable text widgets and put them in the bindings libraries in some fashion.
* The Find panel should work differently; it should highlight all the found strings, and then let you jump back and forth among them.
* The mechanism to display Unix manual pages and URL's should be configurable by the user (e.g. to use TkMan or lynx(l))
* I'd like to support a mechanism for making documents available in multiple languages and selecting the right one, if available, based on a user¡settable or site¡wide preference.
